Commerce Suite AP Setup and Syncing

Commerce Suite AP - Setup Steps

1. Create a Commerce Suite AP API profile in Deacom (Deacom step)

  1. Navigate to the System > Maintenance > API Profiles menu
  2. Click Add.
  3. Enter the following information:
    1. “Name”: enter an appropriate name
    2. “API Category”: select Accounting API
    3. “API Type”: select Commerce Suite
    4. "Key": enter supplied key
    5. "Active": ensure this is checked
  4. Click “Save” when complete.
  5. Once the key is inputted and the API form is saved, a popup form will appear and the following information/credentials will be requested:
    1. Merchant ID
    2. Username
    3. Password
  6. After entering and submitting this information, a "Success" page will appear
  7. Close the popup window.
  8. You should now be connected with Commerce Suite.

Notes:

  • All other fields on this form will be disabled.
  • Only one active Commerce Suite record is allowed at a time in Deacom.

Test vs Production

Test and production setups will be controlled by 2 different one time setup credentials. Since only one active Commerce Suite API Profile is allowed at a time the system will be using either test or production.

When first switching between profiles the initial sync process will need to be done again for the second profile.

Paying a Customer

Payments made to customers(specifically Bill-To records in Deacom) will not be processed through the Commerce Suite automated accounts payable API.

Commerce Suite AP - Syncing Details

Initial Data Sync / Sync All Process

This will be triggered by the ‘Sync All’ button on the API Profiles form.

  • The system will check on the "Sync All" click to validate the current record is already saved since syncing can only occur if the API Profile is saved.
  • See individual syncing sections below on how each of the records should be sent to Commerce Suite, and how we will store their external references.

Vendor Groups

Commerce Suite will need a vendor for each vendor group in the system. The group will represent a single vendor/entity that will be paid in Commerce Suite. The system will still sync the individual vendors in groups to Commerce Suite as well, but when sending invoices or payouts, if the vendor is in a group, that group ID will be used. This is outlined in more detail in the invoice and payout sections. The sync process will:

  • Sync all active vendor groups that do not have a Commerce Suite external reference for the API profile ID.
  • Update all vendor groups, vendor records in Commerce Suite that do have an external reference for the API profile ID.

Vendors

The sync process will:

  • Sync all active vendors to commerce suite that do not have a Commerce Suite external reference for the API profile ID.
  • Update all vendors to commerce suite that do have a Commerce Suite external reference record matching the API profile ID.

Invoices

Invoices will need to be synced after the vendor sync is complete to ensure the vendors exist in Commerce Suite.

The sync process will:

  • Sync all invoiced but not paid purchase orders(ortype = ‘p’) that do not have a commerce suite external reference record for the API profile ID.
    • Exclude any invoice but not paid purchase orders with pre-payment attached.
  • Update all invoiced but not paid purchase orders that do have a Commerce Suite external reference record matching the test mode flag on the profile.

Payouts

No payouts will sync at time of initial setup. These will need to be created once the integration is in place.

When creating payouts in Commerce Suite, they will need to be created based on the vendors preferred payout type. On the vendor record users can set a default payout, which would be either ACH or check. Check is always the fallback if the vendor does not specify differently.

Once we are creating the payouts using the vendors preferred type, the system will then honor the lead time on that payout type. If the user is trying to create a payment that is not in alignment with that lead time window, they should be prompted and the system will prevent the payout from being created. This way the user will know what day they can expect the actual payout to happen.

Example:

If a check lead time is 3 days, and I try to send a check payout today, for today, it should tell me I need at least 3 days of lead time for commerce suite to process.

The expectation is that the users will transact in Deacom using future dates to meet the lead time requirements.

Failed Creates or Updates

Any failed calls will be stored in the API History report. If any occur move past them and sync all data that we can. If failures happen the system will prompt the user at the end of the sync all process that:

“Some vendor records failed to sync. See API History report for details.”

Any data issues can be corrected and either another Sync All process used, or by editing the record and saving the record will by synced to Commerce Suite.

Syncing Vendor and Vendor Group Records

Sync Timing

  1. At initial integration setup – Handled as indicated above
  2. On vendadd or vgrpadd save. (Adding Vendor or Vendor Group records)
    1. If the group or vendor has an external reference for the active Commerce Suite API Profile – Update
    2. If the group or vendor does not have an external reference – Create
  3. EDI or other automatic record creation processes.

Create Vendor Call - Used for vendor groups and vendors

Vendor Group Mapping

  • "externalVendorId": vg_id
  • "vendorName": vg_name
  • "address":
    • "addressLine1": vg_street
    • "addressLine2": vg_street2 + vg_street3
    • "city": vg_city
    • "country": vg_country
    • "state": vg_state
    • "postalCode": vg_zip
  • "contactGivenName": Empty
  • "contactSurname": Empty
  • "emailAddress": vg_email
  • "comment": Empty

Vendor Mapping

The check "remit to" logic will be used here. If the "remit to" information is populated use it, otherwise use the standard vendor fields. This syncing will not include vendor group logic.

  • "externalVendorId": ve_id
  • "vendorName": ve_rname/ve_name
  • "address":
    • "addressLine1": ve_rstreet/ve_street
    • "addressLine2": ve_rstreet2 + ve_rstreet3/ve_street2 + ve_street3
    • "city": ve_rcity/ve_city
    • "country": ve_rcountry/ve_country
    • "state": ve_rstate/ve_state
    • "postalCode": ve_rzip/ve_zip
  • "contactGivenName": ve_rcontact/ve_contact – Send data left of the first space.
  • "contactSurname": ve_rcontact/ve_contact – Send data right of the first space.
  • "emailAddress": ve_remail/ve_email
  • "comment": ve_notes

Our vendor contact field is a single field. It was recommended we try to parse that into a first and last name. We will split on the first space.

Update Vendor/Vendor Group

The update call uses the same fields as creating. The mapping here will be the same.

Vendor/Group Data linkages

Vendor Group

When a vendor group is created in Commerce Suite create a dxexternref record to hold the commerce suite vendor ID.

  • xr_apid – api profile ID.
  • xr_data – Empty
  • xr_id – unique ID
  • xr_recid – vg_id
  • xr_table – dmvgrp
  • xr_xref – Commerce Suite ID returned.

Vendor

When a vendor is created in Commerce Suite create a dxexternref record to hold the Commerce Suite vendor ID.

  • xr_apid – api profile ID.
  • xr_data – Empty
  • xr_id – unique ID
  • xr_recid – ve_id
  • xr_table – dmvend
  • xr_xref – commerce suite ID returned.

Syncing Invoice Records

  1. At Initial integration setup – Handled in setup section
  2. When a PO invoice is entered
    1. Including EDI or other automated invoice processes.
  3. When a PO is un-invoiced

Invoice statuses in Commerce Suite

  • Paid
  • Unpaid
  • Partial

At the time of invoicing, we will generally not know if the customers plan to pay the invoice using Commerce Suite or not. Invoices will be created and updated later to zero balance invoices if payment is made using a non-Commerce Suite payment type.

All invoices created will sync to Commerce Suite regardless of a positive or negative balance.

API Calls

When sending invoices to Commerce Suite the system will identify if the vendor is part of a vendor group or not. When the vendor is part of a vendor group, use the vendor group’s external reference ID to create the invoice. If not part of a group, use the vendor’s external reference ID.

Create Invoice

Handle cases where the vendor does not yet exist in Commerce Suite. We will need to create the vendor and then re-send the invoice create.

  • "invoiceNo": tp_vendinv
  • "date": tp_invvend
  • "dueDate": tp_topay
  • "amount": tp_totdue
  • "balance": tp_balance
  • "comment": tp_remarks
  • "status": Unpaid
  • "purchaseOrderNumber": – tp_purnum. This is a new field being added for integration.

Update/Delete Invoice

Since we will be sending payouts when payments are made in Deacom the orders will only be able to be un-invoiced in our system if they are un-paid in our system. Our logic will prevent un-invoicing if there is a payment/payout in place.

The best process in this case, and the one that will be used, will be to delete invoices in Commerce Suite when un-invoicing in Deacom. Then a new invoice will be created when re-invoicing. This also helps keep invoices out of Commerce Suite if the order is cancelled or changed to something that never will be invoiced.

When an invoice is deleted in commerce suite and un-invoiced, remove the external reference data.

Notes:

  1. The Delete call is not yet built in the integration engine.
  2. In version 17.04.008, the process, when voiding, has been updated. Users will receive a yes/no prompt, enabling them to proceed with un-invoicing in Deacom alone, even if the Commerce Suite cannot process the deletion. This update enhances flexibility and ensures smoother operation within the Deacom system when users need to correct mistakes in Deacom only.

Invoice Data Linkages

When an invoice is created in commerce suite the system will create a dxexternref record to hold the Commerce Suite invoice ID.

  • xr_apid – api profile ID.
  • xr_data – Empty
  • xr_id – unique ID
  • xr_recid – tp_id or tp_purnum
  • xr_table – dttpur
  • xr_xref – commerce suite ID returned.

Payment Types

A new field was added to the dmcash3 table.

  • c3_commercesuite – bit – default to false – Sync payouts to Commerce Suite.

This flag will be used when making ap payments to determine if a payout should be created in Commerce Suite.

Customers will still have some payments that they handle themselves even when set up with Commerce Suite. When this happens, we will not create a payout in their system, and process as a standard payment in Deacom.

When payments are made with a payment type that is not set to sync to Commerce Suite, we will need to update the invoices to be paid and zero balance in Commerce Suite. This will keep a record of the invoice but show that it is not paid in that system.

Cash3add Form Changes

A new checkbox below the "Show in DSD" field captioned ‘Sync Payouts To Commerce Suite’ has been added.

  • Default to false
  • Only visible if an API profile for commerce suite is active (if possible).

Sending Payouts

Payouts will be sent anytime an AP payment is made in the system, using a payment type with c3_commercesuite = true.

  1. Check Run
  2. Manual Checks
  3. During Invoice Entry when Choosing to Pay Now
  4. Vendor Pre-Payment
  5. Vendor Payment on Account
  6. EDI or other automatic payment applications

An invoice must exist in Commerce Suite to send a payout. This will be important for vendor pre-payments and vendor payments on accounts. The other processes should have already had invoices sent to Commerce Suite when the payment is done in system.

Payout Statuses in Commerce Suite

  • Open
  • Complete – Won’t see in test because a payout won’t actually process
  • Scheduled
  • NonConfigured
  • UnConfigured

Invoices tied to a payout can be updated if the payout has any status but complete. Payouts can be updated or deleted in any status but complete.

Check Run and Manual Check

These payouts will be sent when the payment is completed in the system. These payouts should always already have an invoice existing, since we can only apply these payments to invoiced orders.

Vendor Pre-Payments

An invoice will need to exist in Commerce Suite before a payout can be sent. When a pre-payment is applied, the system will first create the invoice(s) for the orders, and then send the payout.

The invoice will be created for the entire order, and then the payouts sent for only what was paid on each order.

When these pre-payments are applied to the order at shipment we will not need to send a payout. The payout is sent when the pre-payment is done is system, and our application does not create another payout.

When orders with pre-payments are received, and then the final invoice entered, we will have an external reference ID for it, and will do an update to ensure that the invoice we have in Commerce Suite now matches the final invoice. From here payouts will be created normally.

Vendor Payment On Accounts

Again, an invoice will need to exist in Commerce Suite before a payout can be sent. When payment on account is made, we create a purchase order in the system. Use the data from this order to create the invoice. Once the invoice is created in Commerce Suite, send over the payout create process.

API Calls

Like with invoices, vendor groups will need to be honored when sending payouts. If the vendor is part of a vendor group, the payout should use the vendor group external reference ID, otherwise use the vendor’s external reference ID.

Create A Payout

  • “paymentId” : dtcash.ca_postref
  • "vendorId": External reference ID. If the vendor is in a group, use the group ID, otherwise the vendors.
  • "transactionNo": dtcash.ca_reference
  • "paymentMethod": Empty – Do we need to update once payout process? And how?
  • "statusDate": ca_recdate
  • "payDate": ca_date
  • "invoices":
    • "invoiceId": External reference ID for the orders paid.
    • "amount": Amount paid on each invoice

Handling Vendor Credits

When vendor credits are applied to invoices to reduce the check total, they will be included in the invoices detail with their appropriate negative balance.

Update/Delete Payouts

Due to the payments being posted in Deacom when we send them to Commerce Suite, revising will use a delete and re-create process similar to invoices. Trying to hold the external reference and update if/when a payment is re-applied will be more complicated than deleting and re-create.

When a payment with an external reference payout is voided in Deacom from the cash disbursements summary, the system will only allow the payment in Deacom to be voided if we can successfully delete in Commerce Suite. Remove the external reference data for the payout, and void normally.

If the payout in Commerce Suite can’t be deleted the money has already been sent. Prompt the user {ok}“Payout has been processed in Commerce Suite, payment can not be voided.”

Note: In version 17.04.008, the process, when voiding, has been updated. Users will receive a yes/no prompt, enabling them to proceed with voiding in Deacom alone, even if the Commerce Suite cannot process the deletion. This update enhances flexibility and ensures smoother operation within the Deacom system when users need to correct mistakes in Deacom only.

Zero Balance Invoices

When a payout is made in Deacom with a payment type that is not sent to Commerce Suite (c3_commercesuite = false), any invoices related to the payout should be updated to a zero-balance type in Commerce Suite.

Use the invoice update call and set the status to “paid’ and the balance to 0.

These invoices should be created as zero balance types in the pre-payment and payment on account process.

Payout Data Linkages

When a payout is created in Commerce Suite, create a dxexternref record to hold the payment ID.

  • xr_apid – api profile ID.
  • xr_data – Empty
  • xr_id – unique ID
  • xr_recid – ca_postref
  • xr_table – dtcash
  • xr_xref – commerce suite ID returned

Commerce Suite Visibility In Deacom

Grid Variance for Commerce Suite ID Visibility

A grid variable named commercesuiteid has been added to the following grids. This should show the external reference ID for the record specified below for the active Commerce Suite integration. This data is in our db and doesn’t require a call to Commerce Suite.

  • mainmain_dmvgrp – Vendor Group
  • Grid_vendmain2 – Vendor
  • chekrun2 – Invoice
  • Grid_paidap and Grid_paidap2 – Invoice
  • Grid_viewcashap – Payout

Grid Variance for Commerce Suite Status Visibility

Only invoices and payouts will have a status in Commerce Suite. Ideally we can show the current Commerce Suite status for these without storing it in system. Add a variable to the following grids named commercesuitestatus. When this variable is on the grid reach out to Commerce Suite to get the statuses of the related records on the grid and show in the variable.

  • chekrun2 – Invoice
  • Grid_paidap and Grid_paidap2 – Invoice
  • Grid_viewcashap – Payout

Deacom/Commerce Suite Reporting Details

The "CommerceSuiteID" and "CommerceSuiteStatus" fields have been added to the following report grids in Deacom to support tracking and reporting on Commerce Suite syncing and related details.

Report Grid

Fields Added

Check To Print (chekrun2)

Commerce Suite ID and Commerce Suite Status

Vendor Groups (vgrpmain)

CommerceSuiteID

Vendors (vendmain2)

CommerceSuiteID

Outstanding Orders (paidap)

Commerce Suite ID and Commerce Suite Status

Invoices To Pay (paidap2)

Commerce Suite ID and Commerce Suite Status

Cash Disbursements (viewcashap)

Commerce Suite ID and Commerce Suite Status

Upgrade Notes

The UpdateAPITypesCommerceSuite popcall program is run when upgrading to version 17.03.009 in order to enable table monitoring for the following tables:

  • Vendors (dmvend)
  • Vendor Group (dmvgrp)
  • Purchase Order Header (dttput)
  • Cash Transactions (dtcash)

API History Report

The API History report via System > History/Performance can be used to both verify and troubleshoot information. The report is accessed when selecting a Type of "API" and a Report Type of "History".

Commerce Suite External Program

The CommerceSuiteSystemSync external program syncs Vendors, Vendor Groups, Invoices (Invoiced Purchase Orders), and Payments with Commerce Suite using the dxexternsync table. The external also has “OnDemand” functions that allow for the following: Invoice status retrieval, Payment status retrieval, and Payment deletion (right before Deacom transaction voids).

Customers will not have access to, or interact with, this external program. The program can be used in certain cases to modify syncing functions. Members of the ECI/Deacom Professional Services Team may work with developers regarding the necessary modifications.